docs: documentation audit — fix license, env var gaps, skill install claims, and missing examples#1103
Draft
cursor[bot] wants to merge 6 commits into
Draft
docs: documentation audit — fix license, env var gaps, skill install claims, and missing examples#1103cursor[bot] wants to merge 6 commits into
cursor[bot] wants to merge 6 commits into
Conversation
The Homebrew formula template in .craft.yml declared the license as FSL-1.1-MIT, but the actual license (LICENSE.md, package.json, README) is FSL-1.1-Apache-2.0. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The agentic-usage page implied that package manager installs (npm, pnpm, bun, yarn) automatically install agent skills. In reality, only curl and Homebrew installs run sentry cli setup automatically — npm has no postinstall hook. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The library usage page said >=22 but package.json engines require >=22.15. Updated both the Requirements section and the comparison table to match. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The proguard.md fragment only covered the uuid subcommand. Added examples for the upload subcommand including multi-file upload, UUID override, and validate-only modes. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The repository structure diagram omitted the references/ directories under both .cursor/skills/ and plugins/sentry-cli/skills/. These contain 26 per-command reference files. Also clarified that SKILL.md is a symlink while references/ are copies synced by CI. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Contributor
|
Contributor
Codecov Results 📊✅ Patch coverage is 100.00%. Project has 5010 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 81.19% 81.20% +0.01%
==========================================
Files 383 383 —
Lines 26651 26651 —
Branches 17354 17354 —
==========================================
+ Hits 21638 21641 +3
- Misses 5013 5010 -3
- Partials 1798 1798 —Generated by Codecov Action |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Audit Report
Full cross-reference of documentation vs. implementation across the Sentry CLI codebase. Covers root docs, command docs/fragments, installation scripts, auth/config code, and the plugin/skills system.
Changes in this PR
.craft.ymlFSL-1.1-MITtoFSL-1.1-Apache-2.0(matchesLICENSE.mdandpackage.json)docs/src/content/docs/agentic-usage.mdsentry cli setup— only curl and Homebrew dodocs/src/content/docs/library-usage.md>=22to>=22.15(matchespackage.jsonengines)docs/src/fragments/commands/proguard.mdproguard uploadexamples (fragment only covereduuid)plugins/README.mdreferences/directories (26 files) and clarified symlink vs copy semanticsFull Gap Report
A. Undocumented or Missing Commands/Subcommands
No structural gaps. All 26 visible top-level routes in
src/app.tshave corresponding fragments indocs/src/fragments/commands/. Generated command docs cover every leaf command automatically from CLI metadata.Hidden routes (
dashboards,events,issues,send-event,send-envelope,bash-hook,whoami, plural aliases) are intentionally excluded from docs.B. Undocumented Flags
No structural gaps in generated docs. Since command docs are generated from CLI introspection, all non-hidden flags appear automatically. Hidden flags (
--verbose,--log-level,--org,--project) are intentionally suppressed.Some fragments could be enriched with notes about less obvious flags:
auth login:--read-only,--scope,--timeout,--urlare in generated docs but not called out in theauth.mdfragment examples — users may not discover themcli setup:--install,--method,--channel,--quietare internal (used by install script/upgrade), correctly absent from fragmentC. Missing Usage Examples
proguard uploaduuidexamplesD. Stale Descriptions
No issues found. Command
briefandfullDescriptionstrings are the source of truth for generated docs, so they cannot drift. Fragment content is additive.E. Missing Route Mappings in Skill Generator
Not applicable.
ROUTE_TO_REFERENCEwas replaced by an automatic 1:1 mapping ingroupRoutesByReference()— every visible route produces its ownreferences/{name}.mdfile. Thehelproute is the only intentional exclusion.F. Installation / Distribution Gaps
FSL-1.1-MITvs actualFSL-1.1-Apache-2.0.craft.ymlline 41LICENSE.md,package.json--no-modify-path,--no-completions,--no-agent-skillsflagsinstallscriptgetting-started.mdx(documented incli.mdfragment)SENTRY_INSTALL_DIRenv varinstallscript,setup.tsinstallOnly), generatedconfiguration.mdSENTRY_INIT=1post-install wizardinstallscriptconfiguration.mdlibstdc++installscriptinstallscript,upgrade.tsG. Undocumented Environment Variables
The
ENV_VAR_REGISTRYinsrc/lib/env-registry.tsis comprehensive and generates theconfiguration.mdpage. Variables in the registry (27 entries) are well-documented.Variables referenced in code but NOT in the registry (intentionally internal):
SENTRY_SCAN_DISABLE_WORKERSSENTRY_ENVIRONMENTSENTRY_LAST_EVENTSENTRY_CLI_NO_EXIT_TRAPSENTRY_MONITOR_SLUGmonitor runchild envSENTRY_TRACES_SAMPLE_RATElocal runchild env*_SENTRY_DSN*_SENTRY_SPOTLIGHTlocal runchild envAssessment: No user-facing env vars are missing from the registry. Internal and SDK-convention variables are appropriately excluded.
H. Auth / Self-Hosted Gaps
.sentryclircURL rejection)src/lib/db/auth.ts,HostScopeError.sentryclircauto-import middleware onnot_authenticatedsrc/lib/rc-import.tsSENTRY_CLIENT_ID_BUILD(build-time hardcoded SaaS client ID)src/lib/oauth.ts--read-onlyand--scopeonauth loginfor self-hostedlogin.tsI. Plugin / Skills Gaps
sentry cli setuppackage.json(no postinstall hook)agentic-usage.mdimplied all installs auto-install skills.cursor/skills/references/are copies, not symlinks (can drift)plugins/README.mdomitted references dirplugins/README.mdrepo diagram incompleteplugins/README.mddocs/public/.well-known/skills/vsplugins/sync not documentedgenerate-skill.tsJ. README / DEVELOPMENT.md Drift
library-usage.mdsays Node>=22, should be>=22.15package.jsonengineslibrary-usage.mdline 218 + comparison tablepnpmcommands, AGENTS.md usesbuncommandsdev-prereq,dev-env-vars,oauth-scopes,build-toolchain,dev-scripts) stay in sync viascript/generate-docs-sections.tslibrary-prereq,dev-prereq,dev-scripts) same mechanismTop 5 Most Impactful Fixes (Prioritized)
Homebrew license mismatch (
.craft.yml) — Every Homebrew install advertises the wrong license. Legal/compliance risk. Fixed.Skill auto-install claim (
agentic-usage.md) — Users installing via npm/pnpm/bun/yarn expect skills to "just work" based on the docs, then find they have no agent integration until they manually runsentry cli setup. Fixed.Node.js version in library-usage.md — Library consumers targeting Node 22.0–22.14 would hit runtime errors that the docs didn't warn about. Fixed.
Host-scoped trust model undocumented (self-hosted.md) — Self-hosted users encounter
HostScopeErrorwhen.sentryclircURLs don't have matching trust anchors, with no documentation explaining the security model or how to resolve it. Recommended for follow-up.Proguard upload missing from fragment — Android developers using ProGuard/R8 mapping uploads had no examples or notes in the docs, only the uuid subcommand was covered. Fixed.